home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / DB_CLIPP / 2614.ZIP / DISPLA.ZIP / DISPLAY.DOC < prev    next >
Text File  |  1990-12-22  |  11KB  |  207 lines
  1.     DispFile() version 5.0                                      23 Dec 1990
  2.  
  3.     DispFile() and assorted routines created by me for the public domain.
  4.  
  5.     DISPLAY.EXE is a self-extracting ZIP file -- see the list at the
  6.     bottom of this doc for details.
  7.  
  8.     Author:         Mike Taylor                 CIS: 73310,3013
  9.                     300 W. Main St.
  10.                     Maple Shade, NJ 08052      Work: (215) 563-9000 x2281
  11.  
  12.  
  13.     Function:
  14.         Summer 87
  15.  
  16.                     DispFile(cInFile, nTop, nLeft, nBottom, nRight,
  17.                              nStart, nCNormal, nCHighlight, cExitKeys,
  18.                              lBrowse, [nColSkip], [nRMargin] )
  19.  
  20.         Clipper 5.0
  21.  
  22.                     DispFile(cInFile, nTop, nLeft, nBottom, nRight,
  23.                              nStart, nCNormal, nCHighlight, cExitKeys,
  24.                              lBrowse, [nColSkip], [nRMargin], [nBuffSize )
  25.     Parameters:  
  26.     
  27.                     cInFile     - text file to display (full name)
  28.                     nTop        - upper row of window
  29.                     nLeft       - left col of window
  30.                     nBottom     - lower row of window
  31.                     nRight      - right col of window
  32.                     nStart      - line to place highlight at startup
  33.                     nCNormal    - normal text color     (numeric attribute)
  34.                     nCHighlight - text highlight color  (numeric attribute)
  35.                     cExitKeys   - terminating keys
  36.                     lBrowse     - browse flag
  37.                     nColSkip    - col increment for left/right arrows
  38.                     nRMargin    - right margin - data is truncated if
  39.                                     it falls to the right of nRMargin.
  40.                                     defaults to 255 if not passed.
  41.                                     for Summer 87 max is 255.
  42.  
  43.                     nBuffSize   - Clipper 5.0 only -- sets the size of
  44.                                     the paging buffer.  defaults to 4096
  45.                                     if not passed.
  46.  
  47.     Returns:        char value - the key that terminated DispFile()
  48.  
  49.     Purpose:        to display a text file within a defined window
  50.                     using as little memory as possible.  the text
  51.                     file to display has to be present or an error
  52.                     value of 0 is returned (as a character.)
  53.  
  54.     ASSUMPTIONS:    the routine assumes that all lines are terminated
  55.                     with a CR/LF sequence (0x0d and 0x0a).
  56.  
  57.                     in the Summer 87 version the page buffer size is 4096
  58.                     chars and the max line length is 255 characters.
  59.  
  60.     Cursor Keys:    Up, Down    - moves the highlight line
  61.                     Left, Right - moves the window over nColSkip col's
  62.                     Home        - moves the window to the far left
  63.                     End         - moves the window to the nRMargin column
  64.                     PgUp, PgDn  - moves the highlight one page
  65.                     Ctrl-PgUp   - moves the highlight to the file top
  66.                     Ctrl-PgDn   - moves the highlight to the file bottom
  67.                     Ctrl-Right  - moves the window 16 col's to the right
  68.                     Ctrl-Left   - moves the window 16 col's to the left
  69.  
  70.                     Esc, Return - terminates the function
  71.  
  72.                     all other keys are ignored unless they are specified
  73.                     within cExitKeys parameter.  This list will tell the
  74.                     routine what keys terminate the function.  Special
  75.                     keys must be passed by a unique value and that value
  76.                     can be found by looking in the keys.h file.  See the
  77.                     test program for an example.
  78.  
  79.     I don't guarantee anything about these routines except that if you find
  80.     a bug or want something changed and you don't have access to a C
  81.     compiler, then give me a shout and I'll see what I can do.
  82.  
  83.     This routine has been compiled with MSC 5.1.  It does utilize the newer
  84.     ANSI C ideas (prototypes, etc.) but all of that has been placed in the
  85.     .h files.  The only part that can be called from Clipper is the main
  86.     routine DispFile().  The screen update code writes directly to screen
  87.     memory and the dispsub.asm file contains the file I/O routines.
  88.  
  89.     If you want to recompile the c code, make sure you define the CLIPPER5
  90.     manifest constant at the head of display.c if you want the Clipper 5.0
  91.     version of DispFile() and then rename the display.obj file to either
  92.     disp_s87.obj or disp_50.obj as required.
  93.  
  94.     WARNING:  If you want to use TLink to link the .obj's then you should
  95.               compile the C routine (display.c) with the appropriate version
  96.               of Turbo C so that the resulting .obj file is 100% compatible.
  97.               Evidently Turbo C's large memory model is not completely
  98.               compatible with Microsoft's.  This problem has not been tested
  99.               completely but one of the 'bugs' vanished whenever I did this.
  100.               Thanks to Gene Winston for discovering this psuedo-bug.
  101.  
  102.     I've tested this routine on the following hardware with no problems:
  103.  
  104.         Gateway 386SX w/VGA mono & color modes
  105.         IBM PC-AT w/mono
  106.         IBM PC-AT w/CGA
  107.         IBM PC-AT w/VGA mono & color modes (Dell VGA Color Plus)
  108.         IBM PS/2 m60 w/VGA mono & color modes
  109.  
  110.     All public symbols are preceded by a 'd_' so you don't have to worry
  111.     about any conflicts with your symbols (unless you happen to have a 'd_'
  112.     in front of any!)
  113.  
  114.  
  115.     Release Notes:
  116.  
  117.         5.0   23 Dec 90   - converted code to run with Clipper 5.0 and S87
  118.                           - removed once again the debug code 
  119.                           - most variables are global for speed reasons
  120.                           - the PgUp/PgDn keys work in a more normal fashion
  121.                               (the highlight stays on the same line and the
  122.                               page changes one full page)
  123.                           - changed all screen i/o asm routines into c code
  124.                               for speed reasons
  125.                           - the 5.0 version uses _xalloc() to grab memory
  126.                               for the page and line buffers
  127.                           - revised documentation
  128.  
  129.         2.1   01 Nov 89   - brought back the debugging code, but this time
  130.                               made it an #ifdef set of clauses that allow
  131.                               the debug info to be written to the mono video
  132.                               area if the cga is active and vice versa.
  133.                               The active video area can be swapped using the
  134.                               F4 key (CodeView people should be happy.)  The
  135.                               .obj files by default have all debug info
  136.                               turned off so if you want it, you'll have to
  137.                               compile
  138.                           - the version also fixed a problem that was
  139.                               occuring when you pressed line_down on some
  140.                               really large files with large line sizes.
  141.                               Thanks to Paul Corrigan and Jack Zakarian at
  142.                               the IMC Systems Group, Inc. for spotting the
  143.                               bug and sending me some sample code to test
  144.  
  145.         2.0   28 Sep 89   - added lBrowse which is a flag to change the
  146.                               way the routine processes the up/down arrows;
  147.                               if it is .T., then the up/down arrows will
  148.                               scroll the window one line up/down and if it
  149.                               is .F., it will screen one line up/down only
  150.                               when the highlight is at the bottom/top of the
  151.                               window
  152.                           - nColSkip and nRMargin will now default to 1 and
  153.                               132 respectively if they are not present in
  154.                               the parameter list
  155.                           - fixed a bug in 1.95 that caused my debugging data
  156.                               to be written to the mono screen (I forgot to
  157.                               comment out the code)
  158.  
  159.         1.95  27 Sep 89   - added nColSkip and nRMargin parameters
  160.  
  161.         1.9   12 Sep 89   - reality check release - recompiled all of the
  162.                               code and retested everything to make sure it
  163.                               all still works.
  164.  
  165.         1.8   17 Mar 89   - set up the keyboard routine to accept a string
  166.                               of char values to terminate the function when
  167.                               pressed
  168.  
  169.         1.7   13 Mar 89   - increased the buffer size to 4096 bytes so that
  170.                               Gene could display one of his files.  It turned
  171.                               out that only 4 or 5 of his lines (> 100 chars)
  172.                               could fit in the buffer and yet for some reason
  173.                               (<g>), the pseudo-window routine was expecting
  174.                               8.  Also rewrote some of the line-up/down code
  175.                               to treat buffer boundaries a little cleaner
  176.                               (not efficient, but easier)
  177.  
  178.         1.6   22 Feb 89   - fixed cursor-past-file-end bug when the file size
  179.                               was within a couple of bytes of the buffer size
  180.                           - fixed some errors in the documentation
  181.  
  182.         1.5   14 Jan 89   - initial release.
  183.  
  184.  
  185.     Files included in DISPLAY.EXE:
  186.  
  187.     DISPLAY  DOC        the file you are reading
  188.  
  189.     DISPLAY  C          contains DispFile() and c routines
  190.     DISPSUB  ASM        contains asm routines
  191.     TEST_S87 PRG        test programs to show DispFile() call
  192.     TEST_50  PRG
  193.  
  194.     DISPLAY  MAK        make file to create DispFile() .obj files
  195.     TEST_S87 MAK        make files to create test program
  196.     TEST_50  MAK
  197.  
  198.     DISPLAY  LNK        sample link file for Blinker
  199.  
  200.     DISP_S87 OBJ        Summer 87 version object file for DispFile()
  201.     DISP_50  OBJ        Clipper 5.0 version object file for DispFile()
  202.     DISPSUB  OBJ        assembler routines object file
  203.  
  204.     DISPLAY  H          include files
  205.     DISPSUB  H
  206.     KEYS     H          include file for key #defines
  207.